org.globalplatform.contactless
Class GPCLSystem

java.lang.Object
  org.globalplatform.contactless.GPCLSystem

public class GPCLSystem
extends java.lang.Object

This class exposes a subset of the behavior of the CRS (OPEN extension) to other on-card components.

Field Summary

static short	AFI_ANY Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for all Contactless applications that belong to any family
static short	AFI_DATA_STORAGE Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Data Storage family
static short	AFI_FINANCIAL Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Financial family
static short	AFI_GAMING Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Gaming family
static short	AFI_IDENTIFICATION Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Identification family
static short	AFI_MEDICAL Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Medical family
static short	AFI_MULTIMEDIA Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Multimedia family
static short	AFI_TELECOMMUNICATION Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Telecommunication family
static short	AFI_TRANSPORT Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Transport family
static short	CARD_INFO_COUNTER_UPDATE The global CRS update counter.
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A The requested information is the CURRENT_PROTOCOL_DATA_TYPE_A (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '86').
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B The requested information is the CURRENT_PROTOCOL_DATA_TYPE_B (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '87').
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F The requested information is the CURRENT_PROTOCOL_DATA_TYPE_F (reserved for future usage).
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_A (i.e. content of INSTALL system parameter Tag '86' when sent to update OPEN parameters).
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_B (i.e. content of INSTALL system parameter Tag '87' when sent to update OPEN parameters).
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_F (reserved for future usage).
static byte	GPCL_CL_APPLICATION The OPEN uses this identifier to retrieve the CLApplet interface implemented by an applet.
static byte	GPCL_CREL_APPLICATION The OPEN uses this identifier to retrieve the CRELApplication interface implemented by an applet.
static byte	GPCL_CRS_APPLICATION The OPEN uses this identifier to retrieve the CRSApplication interface implemented by an applet.
static short	GPCL_INTERFACE_ISO14443 This constant is used with setCommunicationInterface(short, boolean) to manage a ISO14443 based communication interface.

Method Summary

static boolean	checkCommunicationInterfaceAccess(GPRegistryEntry entry, short sInterface) Checks whether a GPRegistryEntry can be accessed through specified communication interface.
static short	getCardCLInfo(byte[] buffer, short offset, short info) Retrieve the OPEN's conctactless parameters.
static GPCLRegistryEntry	getGPCLRegistryEntry(javacard.framework.AID oAID) Gets a reference to a GPCLRegistryEntry interface.
static GPCLRegistryEntry	getNextGPCLRegistryEntry(GPCLRegistryEntry oEntry, short sFamily) Iterates over contactless applets belonging to a particular application family.
static void	setCommunicationInterface(short sInterface, boolean onOff) Switches ON or OFF persistently the specified communication interface at GlobalPlatform card level.
static void	setVolatilePriority(GPCLRegistryEntry oEntry) Sets up or discards the volatile priority.

Methods inherited from class java.lang.Object

equals

Field Detail

GPCL_CL_APPLICATION

public static final byte GPCL_CL_APPLICATION

The OPEN uses this identifier to retrieve the CLApplet interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CRS_APPLICATION

public static final byte GPCL_CRS_APPLICATION

The OPEN uses this identifier to retrieve the CRSApplication interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CREL_APPLICATION

public static final byte GPCL_CREL_APPLICATION

The OPEN uses this identifier to retrieve the CRELApplication interface implemented by an applet.

See Also:

Constant Field Values

AFI_ANY

public static final short AFI_ANY

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for all Contactless applications that belong to any family

See Also:

Constant Field Values

AFI_TRANSPORT

public static final short AFI_TRANSPORT

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Transport family

See Also:

Constant Field Values

AFI_FINANCIAL

public static final short AFI_FINANCIAL

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Financial family

See Also:

Constant Field Values

AFI_IDENTIFICATION

public static final short AFI_IDENTIFICATION

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Identification family

See Also:

Constant Field Values

AFI_TELECOMMUNICATION

public static final short AFI_TELECOMMUNICATION

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Telecommunication family

See Also:

Constant Field Values

AFI_MEDICAL

public static final short AFI_MEDICAL

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Medical family

See Also:

Constant Field Values

AFI_MULTIMEDIA

public static final short AFI_MULTIMEDIA

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Multimedia family

See Also:

Constant Field Values

AFI_GAMING

public static final short AFI_GAMING

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Gaming family

See Also:

Constant Field Values

AFI_DATA_STORAGE

public static final short AFI_DATA_STORAGE

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Data Storage family

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_A (i.e. content of INSTALL system parameter Tag '86' when sent to update OPEN parameters).

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_B (i.e. content of INSTALL system parameter Tag '87' when sent to update OPEN parameters).

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_F (reserved for future usage).

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_A (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '86').

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_B (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '87').

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_F (reserved for future usage).

See Also:

Constant Field Values

CARD_INFO_COUNTER_UPDATE

public static final short CARD_INFO_COUNTER_UPDATE

The global CRS update counter. Each time a GPCLRegistryEntry information is updated, this counter is incremented. Used to indicate off-card applications the need for synchronization.

See Also:

Constant Field Values

GPCL_INTERFACE_ISO14443

public static final short GPCL_INTERFACE_ISO14443

This constant is used with setCommunicationInterface(short, boolean) to manage a ISO14443 based communication interface.

See Also:

Constant Field Values

Method Detail

getGPCLRegistryEntry

public static GPCLRegistryEntry getGPCLRegistryEntry(javacard.framework.AID oAID)

Gets a reference to a GPCLRegistryEntry interface.

Parameters:

oAID - AID of the applet whose GPCLRegistryEntry instance, if available, shall be retrieved. If null, the GPCLRegistryEntry instance corresponding of the applet invoking this method, if available, is returned.

Returns:

the GPCLRegistryEntry interface object, or null

• if there is no applet with the specified AID or,
• if the caller
  • has not GLOBAL REGISTRY privilege, and
  • has not CONTACTLESS ACTIVATION privilege, and
  • is not the Security Domain directly associated with the applet being investigated, and
  • is not the investigated applet itself, and
  • is a not CREL Application registered in the investigated applet's CREL list

getNextGPCLRegistryEntry

public static GPCLRegistryEntry getNextGPCLRegistryEntry(GPCLRegistryEntry oEntry,
                                                         short sFamily)

Iterates over contactless applets belonging to a particular application family.

Contactless applets are those applets that have access to the contactless interface (GPCL_INTERFACE_ISO14443), as specified by Communication Interface Access Parameters (see INSTALL system parameter Tag 'A5' or, if not present, implementation-dependent default OPEN values). This method returns the GPCLRegistryEntry object for the next contactless applet that matches the search criteria. This method shall only return entries corresponding to applets currently having access to the contactless interface.

• Application with GLOBAL REGISTRY privilege can iterate over all contactless Applications.
• Application with CONTACTLESS ACTIVATION privilege can iterate over all contactless Applications.
• A CREL Application can only iterate over its referencing contactless Applications.
• Security Domain can only iterate on its directly or indirectly associated contactless Application(s) unless it has the GLOBAL REGISTRY privilege.

Parameters:

oEntry -

• if oEntry is null, this method returns the first Entry matching the specified family.
• If the list is empty, the method shall return null.
• If oEntry is not null, and represents an application matching the specified family, this method retrieves the next application matching the specified family, otherwise it shall return null.
• If oEntry points to the last application matching the specified family, the method shall return null.

sFamily - the Family Identifier to look for.

Returns:

the reference to the GPCLRegistryEntry interface object of the contactless applet matching the search criteria; null is returned if no application is matching or the end of the list is reached.

Throws:

ISOException - with reason code

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if
  • the caller has not GLOBAL REGISTRY privilege, and
  • the caller has not CONTACTLESS ACTIVATION privilege, and
  • the caller is not a Security Domain or is a Security Domain but the oEntry is not directly associated with this Security Domain, and
  • the caller is not a CREL Application, or is a CRELApplication but the oEntry is not referencing this CREL Application.

java.lang.SecurityException - if oEntry is not a JCRE-owned instance of GPCLRegistryEntry.

See Also:

AFI_ANY, AFI_TRANSPORT, AFI_TELECOMMUNICATION, AFI_MULTIMEDIA, AFI_MEDICAL, AFI_IDENTIFICATION, AFI_GAMING, AFI_FINANCIAL, AFI_DATA_STORAGE

setVolatilePriority

public static void setVolatilePriority(GPCLRegistryEntry oEntry)

Sets up or discards the volatile priority.

Parameters:

oEntry -

• null value discards the volatile priority
• The GPCLRegistryEntry to set in the volatile priority If this entry corresponds to a Head Application, then all applications of corresponding group are part of the volatile priority in the same order as in the GlobalPlatform registry.

Throws:

ISOException - with reason code

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller has not GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION or the GPCLRegistryEntry corresponds to a Member Application

java.lang.SecurityException - if oEntry is not a JCRE-owned instance of GPCLRegistryEntry.

getCardCLInfo

public static short getCardCLInfo(byte[] buffer,
                                  short offset,
                                  short info)

Retrieve the OPEN's conctactless parameters.

Parameters:

buffer - where requested information shall be written

offset - within buffer, where requested information shall be written

info - any CARD_INFO_XX constant.

Returns:

(offset + length of data written in buffer)

Throws:

ArrayIndexOutOfBoundsException - if storing the Application Information bytes would cause access outside array bounds or the offset is negative.

java.lang.NullPointerException - if buffer is null

setCommunicationInterface

public static void setCommunicationInterface(short sInterface,
                                             boolean onOff)

Switches ON or OFF persistently the specified communication interface at GlobalPlatform card level. The technical means for switching an interface ON and OFF are implementation dependent. When the contactless interface is switched off, a reset of the contactless interface shall be performed.

Parameters:

sInterface - GPCL_INTERFACE_ISO14443

onOff - true to switch ON, false to switch OFF

Throws:

ISOException - with reason code

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller has not GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION when managing the GPCL_INTERFACE_ISO14443
• ISO7816.SW_WRONG_DATA if sInterface identifier is not defined.

checkCommunicationInterfaceAccess

public static boolean checkCommunicationInterfaceAccess(GPRegistryEntry entry,
                                                        short sInterface)

Checks whether a GPRegistryEntry can be accessed through specified communication interface.

Parameters:

sInterface - GPCL_INTERFACE_ISO14443

Throws:

ISOException - with reason code

• ISO7816.SW_WRONG_DATA if sInterface identifier is not defined.

Since:

export file version 1.1